Skip to content

docs: simplify README around three processes - #4591

Merged
mnriem merged 2 commits into
github:mainfrom
mnriem:mnriem-readme-simplification
Sep 15, 2026
Merged

mnriem merged 2 commits into
github:mainfrom
mnriem:mnriem-readme-simplification

Conversation

@mnriem

@mnriem mnriem commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Description

Make the README a practical starting point rather than a combined tutorial, reference, and project history. Reduce it from 492 to ~195 lines, with one shared installation/initialization and three independent entry points: Spec-Driven Development, bug fixing, and idea assessment. Process steps are described as skills invoked in the coding agent's chat, with the terminal reserved for CLI installation and project/extension setup.

  • Keep runnable step sequences, Copilot's default skills syntax, the SDD convergence loop, and explicit opt-in installation for bug and assess.
  • Add beginner bug-fixing and assessment walkthroughs, an assessment command reference, and a customization guide.
  • Consolidate detailed command tables and examples, CI initialization guidance, video, anniversary history, community publishing guidance, and dogfooding details into the docs and contributor guide. Reuse existing installation, upgrade, philosophy, and component references rather than duplicating them.
  • Align the docs homepage, reference overview, existing-project guidance, and Chinese README. Retain important README entry anchors and existing SDD walkthrough anchors.
  • Keep acknowledgements in the history page instead of repeating them in the READMEs; retain the license links.
  • Place all three process links under the existing Getting Started navigation group to avoid a reproducible 1024px navbar overflow observed with a separate top-level menu.

Testing

Documentation-only change; no CLI implementation, templates, extension manifests, or catalogs changed.

  • Built the site with DocFX 2.78.5: zero errors, with the same two pre-existing warnings about unsupported ../ glob patterns in docs/docfx.json.
  • Checked all changed Markdown files for rendered destinations and newly broken links/anchors; verified all process pages are reachable from the homepage and navigation.
  • Checked English/Chinese README command-block parity, one shared install/init, all process steps, and opt-in extension setup.
  • Compared rendered upstream and revised homepages at 1440, 1024, 896, 768, 390, and 320px; the final navigation adds no horizontal overflow relative to upstream.

The template's CLI checks are not applicable to this documentation-only change.

AI Disclosure

  • I did use AI assistance (describe below)

GitHub Copilot (models: gpt-6-astra and Claude Opus 4.8), acting on behalf of @mnriem, authored the documentation changes, coordinated translation and an independent review, ran the documentation/browser checks, and fixed the review findings. The human requested and directed the scope; agent execution was autonomous, not human line-by-line authorship. The commits include Assisted-by and Co-authored-by trailers.

mnriem and others added 2 commits September 14, 2026 16:49
Use one shared setup and independent SDD, bug-fixing, and idea-assessment quickstarts. Consolidate detailed content into the docs and contributor guide, add missing process guides, align Chinese documentation, and preserve navigation without widening the site header.

Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Explicitly describe workflow steps as skills invoked in the agent chat, while reserving terminal instructions for CLI installation and project or extension setup.

Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings September 15, 2026 12:52
@mnriem
mnriem merged commit 3affdb2 into github:main Sep 15, 2026
15 checks passed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

Three moderate documentation issues remain unresolved.

Review tier: Lite (auto)
Findings: None

Note

Copilot is running an experiment and ran this review at Lite.

What changed in this PR

This documentation-only PR simplifies onboarding around SDD, bug fixing, and idea assessment.

Changes:

  • Streamlines English and Chinese READMEs.
  • Adds process guides, references, customization guidance, and navigation updates.
  • Moves historical, community, CI, and dogfooding details into dedicated documentation.
File Summary
README.zh-CN.md Updated Chinese onboarding; one moderate anchor-compatibility issue (1 vote).
README.md Simplified process-oriented onboarding; two moderate legacy-anchor issues (1 vote each).
docs/​toc.yml Reorganized documentation navigation.
docs/​reference/​overview.md Documents independent processes.
docs/​reference/​integrations.md Documents invocation formats.
docs/​reference/​bundles.md Clarifies bundle examples and catalog policies.
docs/​reference/​agentic-sdd.md Expands SDD command reference.
docs/​reference/​agentic-bugfix.md Aligns bug-fix reference guidance.
docs/​reference/​agentic-assessment.md Adds assessment command reference.
docs/​README.md Documents the new documentation structure.
docs/​quickstart.md Updates the SDD walkthrough and skills syntax.
docs/​local-development.md Links contributor dogfooding guidance.
docs/​installation.md Consolidates setup and process guidance.
docs/​index.md Reorganizes the documentation homepage.
docs/​history.md Moves historical and acknowledgement content.
docs/​guides/​existing-projects.md Adds independent process guidance; one moderate invocation-syntax issue (1 vote).
docs/​guides/​customization.md Adds customization guidance.
docs/​guides/​bugfix.md Adds bug-fixing walkthrough.
docs/​guides/​assessment.md Adds idea-assessment walkthrough.
docs/​community/​overview.md Adds publishing and trust guidance.
CONTRIBUTING.md Adds dogfooding documentation.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants